# Chapter 14: ISP Hosting

ISP Hosting features provide a way to allot connections to users. If you are an Internet Service Provider (ISP), you can use ISP hosting to deliver streaming media on behalf of your customers.

# Understanding ISP Hosting

Helix Universal Server works with your existing user accounts and directory structure to make users' media files available for streaming. You allocate a minimum and maximum number of connections for each account, based on the number of streams permitted by your license. Allocating on a per- connection basis, rather than by stream, ensures that all files, including SMIL files which reference multiple streams, will always be served.

User account information is stored in a text file, which lists pathing and connection information. List all user account information in a single file, or use separate files to make management easier. Within the user list file, create customized account path and connection information. Or, create a single entry that applies to all user accounts.

## Links to Users' Hosted Content

Links to hosted content have the following format if used in a Web page:

    http://server.example.com:HTTPPort/ramgen/~username/filename.rm

The link which Helix Universal Server uses, or which you can type directly into RealOne Player, has the following format:

    rtsp://server.example.com:RTSPPort/~username/filename.rm

## Account Information

When Helix Universal Server receives a request for streaming media, it looks at user account information, stored in user list files, to determine which user is hosting the requested content.

User list files can list account information separately for each user, or can give generic information that applies to all users.

Each account has three items associated with it:

- Account name

- Virtual path where the account's files will be stored

- Minimum and maximum connections available to the account

Account information is stored in text files, called user list files. You can put all information into a single file or use separate files to make organization easier.

### Connections Available for Each Account

Each account has a reserved number of connections and a maximum number of connections associated with it. The user list file can contain a generic account description that applies to all users, specific instructions about certain accounts, or a combination of the two.

The maximum setting refers to the highest number of connections that will be available for a particular customer's content. Anyone who tries to watch a clip after that account's maximum number of connections are in use will receive an error message, even if connections are available to other accounts.

The number of connections reserved for ISP hosting depends on the type of user record within the user list file:

- Specific user account descriptions

- Generic user account description

If you use a combination of account descriptions, be sure to read both topics in this section.

#### Specific User Accounts

The reserved setting ensures that the specified number of connections will always be available to clients that attempt to view a particular user's hosted media.

All reserved connections are subtracted from the overall number of connections available to Helix Universal Server. The remaining connections are available for non-ISP-hosted content, or for hosted content that hasn't yet been requested. For example, if your Helix Universal Server is licensed for 50 connections, and you reserve 20 connections through the ISP hosting feature, there are 30 connections available for general use. Helix Universal Server can use those remaining connections for streaming regular clips, or for users of ISP-hosted material that isn't yet reserved.

Reserved connections are only activated for accounts listed in the user files, and are activated as soon as Helix Universal Server starts.

| Tip: To guarantee that connections will always be available for certain customers, list those account names in the user file, rather than using a generic scheme. Be careful to leave enough streams available for other use, however.

Users whose accounts are not specifically listed in the user list file default to the generic account description.

#### Generic User Account

For accounts not described in the user list file, minimum connections are not reserved until content is played from a user's account.

#### Other Considerations

It is possible to reserve more connections than are included in your license. In this case, connections are distributed on a first come, first served basis.

For example, if your Helix Universal Server is licensed for 50 connections, and you create a generic account that reserves a minimum of 3 connections for all 25 customers, all the connections will be reserved for ISP hosting customers. Since 75 connections are reserved, but only 50 connections are available, the first 50 customers who connect will be able to play content, but anyone connecting after that will not.

## Tracking Account Usage

Like any content it serves, Helix Universal Server creates a record for each file it serves in the access log. The fourth field in each record of the access log, identified by the `GET` statement, lists the path and filename of each clip served. Compare this information to the path information you've set up to determine how many clips have been streamed from each account.

In most cases, Helix Universal Server creates one record for each clip served. However, SMIL presentations served from your clients' accounts may generate more than one record. You can see which records are part of a SMIL presentation by looking at the final number in the record (present if Logging Style is 5). These numbers will match if they are from the same SMIL presentation. See "SMIL files".

#### Account-Based ISP Hosting

The `GET` statement will include the ISP hosting mount point and the user's account name (beginning with the `~` character). For example, a file with the URL:

    http://server.example.com:HTTPPort/ramgen/~chris/file.rm

would appear in the access log as:

    GET ~chris/file.rm

#### Dedicated ISP Hosting

Because dedicated ISP hosting Helix Universal Servers can only stream content for users, and not stream any other type of content, the access log will only show material streamed for ISP customers. The mount point will always appear.

The GET statements will show the directory portion of the URL.

A file with the following URL:

    http://server.example.com:HTTPport/ramgen/r/ra/rabrams/file.rm

would appear in the access log as:

    GET r/ra/rabrams/file.rm

## Dedicating Helix Universal Server to ISP Hosting

Helix Universal Server can be dedicated to only serving hosted content. If you use this option, Helix Universal Server cannot stream media files from any other directories.

This option requires that users' directories are arranged in a hierarchy. Features available in dedicated hosting are the same as in account-based hosting.

URLs used in this type of hosting have a different format. Rather than use a tilde (~) to alert Helix Universal Server to an upcoming ISP request, this method relies on a directory structure shown in the URL.

    http://server.example.com:HTTPPort/ramgen/s/sa/sandy/media/filename.rm

or

    rtsp://server.example.com:RTSPPort/s/sa/sandy/media/filename.rm

A comparison of the two styles is shown below. Use only one style on a particular Helix Universal Server.

Comparison of Account Identification Styles
Issue | Account-Based Hosting | Dedicated Hosting
--- | --- | ---
Hosted material | Can host content for ISP users; can also serve ordinary streamed content. | Can only host content from user accounts. Cannot serve other content.
User directory structure | Works with any directory structure; enables different structures or locations. Users may have their own subdirectories. | Works with a hierarchical directory structure, especially an alphabetic one. Organization of directories must be the same for all users. Users may have their own subdirectories.
Reserving connections | Can reserve number of connections available for material streamed from certain accounts. | Cannot guarantee any reserved connections.
User settings | Some users can have customized settings, while generic connection settings describe all other users. | All users have identical settings.

## Compatibility with Earlier Versions of RealSystem Server

If you used ISP Hosting in RealSystem Server versions 3 through 5, you can still use the UserList from your previous configuration file. Refer to "Creating User Lists From Earlier Versions" for instructions on how to use your existing UserList.

Earlier versions of RealSystem Server listed minimum and maximum settings for the number of streams available to each account. In Helix Universal Server version 9.0, those settings now refer to the number of connections available to each account. This enables customers to serve SMIL files—which may reference several streams simultaneously—without running out of streams.

This manual uses new terminology for the methods of referring to account structures described in editions of RealServer Administration Guide previous to version 8.

- "Naming Convention One" is now described as the usual method of configuring user list files.

- "Naming Convention Two" is described here as a dedicated hosting Helix Universal Server, a special case.

Although they have different names in this manual, the user directory structures and user list structures in each method are functionally identical to the methods used in earlier versions of RealSystem Server.

## Example ISP Hosting Scenario—Northwest ISP

Throughout this chapter, we'll use the example of an ISP who sets up Helix Universal Server to host its users' media files. Northwest ISP hosts content for customers in a three-state area in the United States' Pacific Northwest. Users' directories are organized according to the state in which the users live— Washington, Oregon, and Idaho:

    C:\home\washington
    C:\home\oregon
    C:\home\idaho

Individual accounts are located immediately below these directories:

Chris Anderson's account:

    C:\home\washington\canderson

Pat Brown's account:

    C:\home\washington\pbrown

Lee Adams' account:

    C:\home\oregon\ladams

Sandy Chu's account:

    C:\home\oregon\schu

Other accounts:

    C:\home\idaho\alex

    C:\home\idaho\sam

    C:\home\idaho\tracy

The links to these users' files look different than other Helix Universal Server links. These all contain a tilde (~) and the user's usernames or account names:

`http://server.example.com:HTTPport/ramgen/~chris/file.rm`
`http://server.example.com:HTTPport/ramgen/~lee/file.rm`
`http://server.example.com:HTTPport/ramgen/~pat/file.rm`
`http://server.example.com:HTTPport/ramgen/~sandy/file.rm`

# Users' Directory Structures

Helix Universal Server matches your existing directory locations of users' files, even if you use different structures for different users. Typically, user directories are named with the username of the account; the username is included in the URL.

Customers' media files are stored in their directories. If they place files in a subdirectory of their main directory, that subdirectory must be included in the URL.

### Directory Structures in Dedicated Hosting

A Helix Universal Server used exclusively for hosting users' streamed media from accounts based on a strict directory structure uses an alternate method of identifying accounts. In the user list, you identify how far down the directory path to look for individual user accounts; this requires that the accounts must all be at the same level.

In the following example, accounts are divided into separate directories, according to an alphabetic arrangement:

    ...
    /UserAccounts/r/ra/rabrams
    /UserAccounts/r/ra/radams
    ...
    /UserAccounts/s/sa/sanderson
    /UserAccounts/s/sb/sbraun
    /UserAccounts/s/sb/sbrown
    /UserAccounts/s/sc/schu
    ...

Users may have their own subdirectories. If they place files in a subdirectory of their main directory, that subdirectory must be included in the URL.

Of course, if you use the account-based style of identifying customer directories rather than the method described in this section, you can also dedicate Helix Universal Server to only hosting streamed media for customers, but other streaming options are still available.

# Setting Up ISP Hosting

There are three steps for configuring Helix Universal Server to host users' media files:

1. Create the user list file.

This file establishes account information, such as reserved connections and maximum connections. For more information, see "Creating the User List".

2. Configure Helix Universal Server.

The configuration file indicates where to find the user lists, and completes the pathing information needed to located the users' media. For more information, see "Configuring Helix Universal Server".

3. Creating the links to content.

You will need to tell customers what format they should use in creating their links. For more information, see "Linking to ISP Content".

## Creating the User List

Create the user list, and store it anywhere that is accessible to Helix Universal Server.

The user list is a text file with the following format:

`UserList [
{``account``, /``path``/,` `minimum_connections``,` `maximum_connections``}`

`]`

where:

`account` is either a specific user name, or `~*` to indicate that all accounts will use the same settings. See "Using Multiple User List Files" for examples of how multiple accounts can be shown in a user list.

| Note: Dedicated hosting Helix Universal Servers use a slightly different format. Refer to "Dedicated Hosting User File Format" for the correct format to use.

`/``path``/` gives information about the location of users' media files. It does not necessarily refer to an actual location or portion of a location; instead, it is a logical method of grouping the users.

`minimum_connections` is the minimum number of connections reserved for this user. `0` indicates that no connections are reserved. See "Connections Available for Each Account" for more information.

`maximum_connections` is the maximum number of connections available to this user. `0` indicates that no connections may be used. See "Connections Available for Each Account" for more information.

| Tip: You can include comments in the file by preceding a line with a semi-colon (;).

### Example—User List File

In this user list file (shown in the left column of the table), users are grouped according to their geographic location. Two users, Chris and Pat, are in the Washington (wa) group. Two other users, Lee and Sandy, are in the Oregon group.

Sample User List
User List File Contents | Matching Customer Name
--- | ---
`UserList [` |
`{chris, /wa/canderson/, 2, 5},` | Chris Anderson
`{lee, /or/ladams/, 0, 100},` | Lee Adams
`{pat, /wa/pbrown/, 2, 50},` | Pat Brown
`{sandy, /or/schu/, 1, 35},` | Sandy Chu
`]` |

### Listing Individual Accounts

If each account has different settings, create a separate record for each user, as in the example above.

### Listing Generic Accounts

If you have a large number of accounts to create, and they will all use the same number of connections, create a single entry that refers to all accounts generically:

`UserList [
{~*, /``path``/,` `minimum_connections``,` `maximum_connections``}
]`

In the following example, one connection is reserved for each person, and the maximum number of connections available for any account is 35. (There are some restrictions on whether the connections are actually reserved; see "Connections Available for Each Account".)

    UserList [
    {~*, /users/, 1, 35}
    ]

### Combining Individual Account Listings with a Generic Listing

Custom account information and generic settings can be combined in a single user list. Combining them is convenient if most users have the same settings, but a few have different number of connections reserved, or use different paths:

`UserList [
{``username1``, /``path``/,` `minimum_connections``,` `maximum_connections``}
{``username` `2, /``path``/,` `minimum_connections``,` `maximum_connections``}
{``username` `3, /``path``/,` `minimum_connections``,` `maximum_connections``}
...
{~*, /``path``/,` `minimum_connections``,` `maximum_connections``}
]`

In the following example, customized accounts for four users have been created, and all other accounts will use the default settings shown in the last entry:

Sample User List
User List | Customer Name
--- | ---
`UserList [` |
`{chris, /wa/canderson/, 2, 5},` | Chris Anderson
`{lee, /or/ladams/, 0, 100},` | Lee Adams
`{pat, /wa/pbrown/, 1, 35},` | Pat Brown
`{sandy, /or/schu/, 1, 5},` | Sandy Chu
`{~*, /id/, 1, 35}` | All others not specified above
`]` |

### Using Multiple User List Files

You can create as many user lists as you want; using multiple files can make administration easier. For example, an ISP provider might include commercial accounts in one user list file and personal accounts in another file.

Helix Universal Server loads the user lists in the order they appear in the configuration file, and any settings in subsequent files override settings in previously-loaded files. If the same user name appears in more than one list, Helix Universal Server uses the settings in the last user list.

Because of this behavior, bear in mind the following considerations when using multiple user list files:

- An account name must not appear in more than one file.

- The generic account information (an entry beginning with `~*`) must be used carefully. Include it only in the first-loaded user list file. If you include it in the last file, Helix Universal Server will ignore all the other user lists.

### Re-Reading an Updated User List File

Once you have created the user list file and the ISP hosting feature is in use, you must instruct Helix Universal Server to re-read the user list.

- On Windows-based platforms, after you edit a user list file, you must restart Helix Universal Server for the changes to take effect.

- On UNIX-based platforms, you can use the SIGHUP command to instruct Helix Universal Server to re-read the user list files. See "Helix Universal Server Restart"

### Dedicated Hosting User File Format

The format of the user list file in dedicated hosting is nearly the same as the account-based method, with these exceptions:

- Create only one user file. You cannot use more than one with the dedicated hosting server.

- Create only one entry in the user file. This entry applies to all user accounts.

- Instead of giving an account name, you indicate how far to traverse the user directory structure in order to find the unique user directories.

Use the following format:

    UserList [
    {*n, /path/, minimum_connections, maximum_connections}
    ]

where `n` is a number that represents the level of directory at which individual user directories appear.

#### Example

In the following example, all user accounts are located under a subdirectory of the UserAccounts directory. The unique directories are located at the fourth directory level (rabrams, radams, sanderson, and so on).

    ...
    /UserAccounts/r/ra/rabrams
    /UserAccounts/r/ra/radams
    ...
    /UserAccounts/s/sa/sanderson
    /UserAccounts/s/sb/sbraun
    /UserAccounts/s/sb/sbrown
    /UserAccounts/s/sc/schu
    ...

The user list for this example uses `4` for the value of `n`:

    UserList [
    {*4, /UserAccounts/, 1, 15}
    ]

URLS created with this method have the following format:

    rtsp://server.example.com:554/directory1/directory2/directory3/filename

For example, `rtsp://server.example.com:554/UserAccounts/r/ra/rabrams/band.rm`

### Creating User Lists From Earlier Versions

Recycle your UserList entry from the configuration file of earlier versions. If your UserList is long, you may want to create more than one file.

After you create the new user list file, follow the instructions in "Configuring Helix Universal Server".

| To create a user list from existing settings:

1. Open your old configuration file in a text editor.

2. Locate the `UserList` entry.

3. Copy and paste the existing `UserList` setting into a new text file.

4. Save the file. You can store it in any directory that is available to Helix Universal Server.

Another item from the previous configuration file, `UserDir`, does not have an equivalent.

## Configuring Helix Universal Server

You will need to make a note of the values for `/path/` that you used in the user list file.

These instructions describe how to create a separate mount point for each customer category, which means customer files can be stored in separate base paths or drives.

| To configure Helix Universal Server for ISP Hosting:

1. First, look in the user list files at the `/path/` settings you have used. You will need this information in Step 11.

2. Click Server Setup>Mount Points.

You will add a mount point for each path in the User List file, give it a name, and indicate a base path.

3. Click the "+" icon and enter a mount point description in the Edit Description box.

4. In the Mount Point box, type a name for the new mount point.

In our example, type `/wa_isp/`.

5. In the Base Path box, type the location in which these paths should be mapped.

In our example, type `C:\home\washington`.

6. Repeat Step 3 through Step 5 for each mount point and base path combination.

In our example, we used the following settings:

Example Settings
Mount Point | Description | Base Path
--- | --- | ---
`/wa_isp/` | `ISP Content (Washington users)` | `C:\home\washington`
`/or_isp/` | `ISP Content (Oregon users)` | `C:\home\oregon`
`/id_isp/` | `ISP Content (Idaho users)` | `C:\home\idaho`

7. Click Apply.

8. Click Content Management>ISP Hosting.

9. In the Translation Mounts area, click the "+" icon and type a description in the Edit Translation Mount Description box.

10. From the Mount Point list, select the mount point that you want to use for this Translation Mount. (You created these in Step 2 through Step 6.)

11. In the User Path box, type the value of `/path/` from the user list file.

For each `/path/` that appears in the user list file, repeat Step 9 through Step 11 to associate the `/path/` with a translation mount.

In our example, we have created a separate user path for `/wa/`, for `/or/`, and for `/id/`.

Example User Paths
Translation Mount Description | Mount Point | User Path
--- | --- | ---
`Washington users` | `/wa_isp/` | `/wa/`
`Oregon users` | `/or_isp/` | `/or/`
`Idaho users` | `/id_isp/` | `/id/`

12. In the User List files section, click the "+" icon. A generic user list name appears in the Edit User List File Name box. Type the correct path to the user list you created in "Creating the User List". Be sure to give the full path. To add more than one user list this for each list you want to add. In dedicated hosting, reference only one user list file.

13. Click Apply.

## Linking to ISP Content

You'll need to tell your customers what format to use for their links.

Links in a Web page use this format:

    http://address:HTTPPort/ramgen/~account/path/file

Helix Universal Server URL Components
Component | Meaning
--- | ---
`http` | The protocol used to initiate streaming.
`address` | Machine and domain name of Helix Universal Server. IP address may be substituted.
`HTTPPort` | Port number where Helix Universal Server listens for requests sent via the protocol listed at the beginning of the URL. This value is usually `80` or `8080`; see "Defining Communications Ports".
`ramgen` | Required when you link in a Web page.
`account` | User's account name.
`ramgen` | The mount point tells Helix Universal Server how the clip should be served.
`path` | Optional.
`file` | The file name itself, including the extension.

For samples of links to use in the Web page, see "Example ISP Hosting Scenario—Northwest ISP".

Links typed directly in the player or used in a Ram or SMIL file use the following format:

    rtsp://address:RTSPPort/~account/path/file

The format is nearly the same as the link used in the Web page: the protocol is different, the port number (if any) matches the protocol, and Ramgen is omitted.

### Dedicated Hosting Server

Links in a Web page use this format:

    http://address:HTTPPort/ramgen/directory1/directory2/path/file

where:

Helix Universal Server URL Components
Component | Meaning
--- | ---
`http` | The protocol used to initiate streaming.
`address` | Machine and domain name of Helix Universal Server. IP address may be substituted.
`HTTPPort` | Port number where Helix Universal Server listens for requests sent via the protocol listed at the beginning of the URL. This value is usually `80` or `8080`; see "Defining Communications Ports".
`ramgen` | The mount point tells Helix Universal Server how the clip should be served.
`directory1` | Each directory that is part of the hierarchy of directories. The number of directories you list must match the `n` number in the user list file.
`directory2`
`path` | Optional. Represents any subdirectories of the user's home directory.
`file` | The file name itself, including the extension.

Using the example in "Dedicated Hosting User File Format", a link to `file.rm` in the user directory `/UserAccounts/r/ra/rabrams` would look like the following:

    http://server.example.com:HTTPport/ramgen/r/ra/rabrams/file.rm

## ISP Hosting Used with Other Features

Users inherit many features of your Helix Universal Server: hosting of on- demand content, and access control are available.

Other Feature | Notes
--- | ---
Authentication | Not available for hosted material.
Live unicasting, multicasting, and splitting. | Not available for hosted material.
Monitoring statistics | As the administrator, you are able to view how many clients are connected to all material served by your Helix Universal Server, using Server Monitor. In order to discern which material belongs to users, you must examine the paths of the individual clips in use. You also can see which clips have been served by reading the access log file.
Helix Universal Proxy | Helix Universal Proxy is able to cache your users' content, just as it can cache any on-demand files served by this Helix Universal Server.

| © 2002 RealNetworks, Inc. All rights reserved. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.